home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / program / revup1_4.lha / RevUp.guide (.txt) < prev    next >
Amigaguide Document  |  1996-01-08  |  19KB  |  470 lines
  1. @DATABASE "RevUp Documentation"
  2. @AUTHOR   "Boris Folgmann"
  3. @(C)      "(C) 1994-1996 PROXITY SOFTWORKS"
  4. @$VER: RevUp.guide 1.4 (8.1.96)
  5. @WORDWRAP
  6. @INDEX "Index"
  7. ###########################################################################
  8. @NODE MAIN "RevUp""
  9.                    @{b}RevUp@{ub} - Amiga Revision Update System
  10.             Freeware 
  11.  1994-1996 by @{"PROXITY SOFTWORKS" LINK "PSI/PROXITY SOFTWORKS"}
  12.                   Development by @{"Boris Folgmann" LINK "PSI/Boris Folgmann"}
  13.     RevUp 1.4 (8.1.96)    User Manual
  14.     @{" Copyrights          " LINK COPYRIGHTS}    Copyright information.
  15.     @{" Disclaimer          " LINK PSI/DISCLAIMER}    Legal stuff.
  16.     @{" Description         " LINK DESCRIPTION}    What does it?
  17.     @{" System requirements " LINK REQUIREMENTS}    What do you need to run it?
  18.     @{" Contents            " LINK CONTENTS}    Archive contents.
  19.     @{" Installation        " LINK INSTALLATION}    How to install.
  20.     @{" Usage               " LINK USAGE}    How is it used?
  21.     @{" History             " LINK HISTORY}    What's new?
  22.     @{" Support             " LINK PSI/SUPPORT}    How to contact us.
  23.     @{" Update              " LINK PSI/UPDATE}    Where to get new releases.
  24.     @{" Credits             " LINK PSI/CREDITS}    Thanks to some persons.
  25. @ENDNODE
  26. ###########################################################################
  27. @NODE "COPYRIGHTS" "Copyright Information"
  28.                                 COPYRIGHTS
  29.                    Unless otherwise noted, all files are
  30.                  Freeware 
  31.  1994-1996 by @{"PROXITY SOFTWORKS" LINK "PSI/PROXITY SOFTWORKS"}
  32.                            All Rights Reserved.
  33.                      MagicWB 
  34.  1994 Martin Huttenloher
  35.              Kickstart and Workbench are Copyright 
  36.  1985-1996
  37.                                  ESCOM AG
  38. @ENDNODE
  39. ###########################################################################
  40. @NODE "DESCRIPTION" "What does it?"
  41.                                 DESCRIPTION
  42.  o RevUp generates and maintains include and header files with revision
  43.    information.
  44.  o Basically RevUp is similar to the developer tool BumpRev, but it
  45.    offers a lot of additional features.
  46.  o ANSI-C, Oberon and Assembly language supported.
  47.  o Multiple dependency files.
  48.  o Beta count management for beta versions included.
  49.  o Interactive logfile generation.
  50. @ENDNODE
  51. ###########################################################################
  52. @NODE "REQUIREMENTS" "What do you need to run it?"
  53.                             SYSTEM REQUIREMENTS
  54. @{"Kickstart" LINK COPYRIGHTS} 2.04
  55. @{"Workbench" LINK COPYRIGHTS} 2.0
  56. @{"Workbench" LINK COPYRIGHTS} 2.1 for localized DOS error messages.
  57. @ENDNODE
  58. ###########################################################################
  59. @NODE "CONTENTS" "Archive Contents"
  60.                                  CONTENTS
  61. This software package consists of the following files:
  62. @{FG HIGHLIGHT}RevUp@{FG TEXT}
  63.     The executable shell command.
  64. @{FG HIGHLIGHT}RevUp_rev.log@{FG TEXT}
  65.     RevUp's revision logfile generated by using the @{"LOG" LINK "LOG"} switch.
  66. @{FG HIGHLIGHT}RevUp.guide@{FG TEXT}
  67.     This AmigaGuide document for Multiview.
  68. @{FG HIGHLIGHT}PSI@{FG TEXT}
  69.     @{"Proxity Softworks" LINK "PSI/PROXITY SOFTWORKS"} information text.
  70. All icons are part of @{"MagicWB" LINK COPYRIGHTS} and included with permission of the author.
  71. @ENDNODE
  72. ###########################################################################
  73. @NODE "INSTALLATION" "How to install"
  74.                                INSTALLATION
  75. Simply copy RevUp to a directory in your path. Place this documentation
  76. where you want.
  77. For example type:
  78.     @{fg highlight}copy RevUp to C:
  79.     copy RevUp.guide to HELP:english/@{fg text}
  80. @ENDNODE
  81. ###########################################################################
  82. @NODE "USAGE" "How is it used?"
  83.                                    USAGE
  84. Usage:    RevUp <version> <projectname> {<dependency>} [REV <revision>]
  85.               [BETA] [C] [ASM] [OBERON] [LOG] [EXTRA] [ENVVAR] [TINY]
  86. @{u}Required@{uu}
  87.   @{" VERSION/N      " LINK VERSION} Version number.
  88.   @{" PROJECTNAME/A  " LINK PROJECTNAME} Name of the project.
  89.   @{" DEPENDENCIES/M " LINK DEPENDENCIES} Files which dates are checked.
  90. @{u}Optional@{uu}
  91.   @{" REV/K/N        " LINK REVISION} Explicit revision number.
  92.   @{" BETA/S         " LINK BETA} Generate beta information.
  93.   @{" C/S            " LINK C} Generate C headerfile (default).
  94.   @{" ASM/S          " LINK ASM} Generate Assembly includefile.
  95.   @{" OBERON/S       " LINK OBERON} Generate Oberon definition module.
  96.   @{" LOG/S          " LINK LOG} Interactively add history info to logfile.
  97.   @{" EXTRA/S        " LINK EXTRA} Generate extra information.
  98.   @{" ENVVAR/S       " LINK ENVVAR} Set envvar for archive naming.
  99.   @{" TINY/S         " LINK TINY} Don't print credits.
  100. Start RevUp without any arguments to get the above short description.
  101. RevUp uses a revision storage file which contains the current revision
  102. number. Therefore it's possible to increment the revision number on every
  103. invocation of the program.
  104. Look at the example smakefile for SuperTool to get an impression how RevUp
  105. is used.
  106. @{fg highlight}SuperTool: SuperTool.c SCOPTIONS SMAKEFILE
  107.     @RevUp 1 SuperTool SuperTool.c EXTRA BETA
  108.     sc SuperTool.c
  109. RELEASE:
  110.     @RevUp 1 SuperTool EXTRA LOG
  111.     sc SuperTool.c NODEBUG OPT@{fg text}
  112. Now have a look at the generated file @{"SuperTool_rev.h" LINK HEADERBETA}.
  113. Call @{FG HIGHLIGHT}smake RELEASE @{FG TEXT} to get the file without beta information:
  114. @{"SuperTool_rev.h" LINK HEADER}.
  115. Note that all definitions from TIME to HOST are only added if @{"EXTRA" LINK EXTRA} is
  116. specified.
  117. BASENAME is the project name in capital letters, e.g. 'MYTOOL'. Useful for
  118. ARexx port or public screen naming. Note that language-sensitive functions
  119. are used to convert to upper case if locale.library is present on your
  120. system.
  121. USER and HOST are imported from the environment variables USERNAME and
  122. HOSTNAME which are mentioned in the Amiga User Interface Style Guide.
  123. To enable AmiTech's VERSION command to display version information about
  124. your program you have to put VERSTAG in your code.
  125. Example for SuperTool in C:
  126. @{FG HIGHLIGHT}#include    "SuperTool_rev.h"
  127. const static char VersTag[] = VERSTAG;
  128. @{FG TEXT}
  129. Example for SuperTool in Assembly language:
  130. @{FG HIGHLIGHT}
  131.         INCLUDE    "SuperTool_rev.i"
  132. VersTag:    VERSTAG
  133. @{FG TEXT}
  134. @ENDNODE
  135. ###########################################################################
  136. @NODE "MODULE"
  137. (* Oberon definition module generated by RevUp 1.3 *)
  138. MODULE SuperToolRev;
  139.     IMPORT SYSTEM;
  140. CONST
  141.     VERSION        - = 1;
  142.     REVISION    - = 1;
  143.     DATE        - = "19.9.95";
  144.     VERS        - = "SuperTool 1.1";
  145.     VSTRING        - = "SuperTool 1.1 (19.9.95)\\r\\n";
  146.     VERSTAG        - = "\\o$VER: SuperTool 1.1 (19.9.95)";
  147.     TIME        - = "00:30:11";
  148.     PRGNAME        - = "SuperTool";
  149.     BASENAME    - = "SUPERTOOL";
  150.     VSTR        - = "SuperTool 1.1 (19.9.95)";
  151.     USER        - = "boris"
  152.     HOST        - = "prox"
  153. BEGIN
  154.     IF SYSTEM.ADR (VERSTAG) # NIL THEN END
  155. END SuperToolRev.
  156. @ENDNODE
  157. ###########################################################################
  158. @NODE "INCLUDE"
  159. ;* Assembly includefile generated by RevUp 1.3 *
  160. VERSION        EQU    1
  161. REVISION    EQU    1
  162. DATE    MACRO
  163.         dc.b    '12.7.95'
  164.         ENDM
  165. VERS    MACRO
  166.         dc.b    'SuperTool 1.1'
  167.     ENDM
  168. VSTRING    MACRO
  169.         dc.b    'SuperTool 1.1 (12.7.95)',13,10,0
  170.     ENDM
  171. VERSTAG    MACRO
  172.         dc.b    0,'$VER: SuperTool 1.1 (12.7.95)',0
  173.     ENDM
  174. TIME    MACRO
  175.         dc.b    '14:57:51'
  176.     ENDM
  177. PRGNAME    MACRO
  178.         dc.b    'SuperTool'
  179.     ENDM
  180. BASENAME    MACRO
  181.         dc.b    'SUPERTOOL'
  182.     ENDM
  183. VSTR    MACRO
  184.         dc.b    'SuperTool 1.1 (12.7.95)'
  185.     ENDM
  186. USER    MACRO
  187.         dc.b    'boris'
  188.     ENDM
  189. HOST    MACRO
  190.         dc.b    'prox'
  191.     ENDM
  192. @ENDNODE
  193. ###########################################################################
  194. @NODE "HEADER"
  195. /* C headerfile generated by RevUp 1.3 */
  196. #define VERSION        1
  197. #define REVISION    1
  198. #define DATE    "12.7.95"
  199. #define VERS    "SuperTool 1.1"
  200. #define VSTRING    "SuperTool 1.1 (12.7.95)\\r\\n"
  201. #define VERSTAG    "\\0$VER: SuperTool 1.1 (12.7.95)"
  202. #define TIME    "14:57:51"
  203. #define PRGNAME    "SuperTool"
  204. #define BASENAME    "SUPERTOOL"
  205. #define VSTR    "SuperTool 1.1 (12.7.95)"
  206. #define USER    "boris"
  207. #define HOST    "prox"
  208. @ENDNODE
  209. ###########################################################################
  210. @NODE "MODULEBETA"
  211. (* Oberon definition module generated by RevUp 1.3 *)
  212. MODULE SuperToolRev;
  213.     IMPORT SYSTEM;
  214. CONST
  215.     VERSION        - = 1;
  216.     REVISION    - = 2;
  217.     BETA        - = 1;
  218.     DATE        - = "19.9.95";
  219.     VERS        - = "SuperTool 1.2 BETA 1";
  220.     VSTRING        - = "SuperTool 1.2 BETA 1 (19.9.95)\\r\\n";
  221.     VERSTAG        - = "\\o$VER: SuperTool 1.2 BETA 1 (19.9.95)";
  222.     TIME        - = "00:31:26";
  223.     PRGNAME        - = "SuperTool";
  224.     BASENAME    - = "SUPERTOOL";
  225.     VSTR        - = "SuperTool 1.2 BETA 1 (19.9.95)";
  226.     USER        - = "boris"
  227.     HOST        - = "prox"
  228. BEGIN
  229.     IF SYSTEM.ADR (VERSTAG) # NIL THEN END
  230. END SuperToolRev.
  231. @ENDNODE
  232. ###########################################################################
  233. @NODE "INCLUDEBETA"
  234. ;* Assembly includefile generated by RevUp 1.3 *
  235. VERSION        EQU    1
  236. REVISION    EQU    2
  237. BETA    EQU 1
  238. DATE    MACRO
  239.         dc.b    '12.7.95'
  240.     ENDM
  241. VERS    MACRO
  242.         dc.b    'SuperTool 1.2 BETA 1'
  243.     ENDM
  244. VSTRING    MACRO
  245.         dc.b    'SuperTool 1.2 BETA 1 (12.7.95)',13,10,0
  246.     ENDM
  247. VERSTAG    MACRO
  248.         dc.b    0,'$VER: SuperTool 1.2 BETA 1 (12.7.95)',0
  249.     ENDM
  250. TIME    MACRO
  251.         dc.b    '14:58:29'
  252.     ENDM
  253. PRGNAME    MACRO
  254.         dc.b    'SuperTool'
  255.     ENDM
  256. BASENAME    MACRO
  257.         dc.b    'SUPERTOOL'
  258.     ENDM
  259. VSTR    MACRO
  260.         dc.b    'SuperTool 1.2 BETA 1 (12.7.95)'
  261.     ENDM
  262. USER    MACRO
  263.         dc.b    'boris'
  264.     ENDM
  265. HOST    MACRO
  266.         dc.b    'prox'
  267.     ENDM
  268. @ENDNODE
  269. ###########################################################################
  270. @NODE "HEADERBETA"
  271. /* C headerfile generated by RevUp 1.3 */
  272. #define VERSION        1
  273. #define REVISION    2
  274. #define BETA    1
  275. #define DATE    "12.7.95"
  276. #define VERS    "SuperTool 1.2 BETA 1"
  277. #define VSTRING    "SuperTool 1.2 BETA 1 (12.7.95)\\r\\n"
  278. #define VERSTAG    "\\0$VER: SuperTool 1.2 BETA 1 (12.7.95)"
  279. #define TIME    "14:58:29"
  280. #define PRGNAME    "SuperTool"
  281. #define BASENAME    "SUPERTOOL"
  282. #define VSTR    "SuperTool 1.2 BETA 1 (12.7.95)"
  283. #define USER    "boris"
  284. #define HOST    "prox"
  285. @ENDNODE
  286. ###########################################################################
  287. @NODE "VERSION"
  288.                                  VERSION/N
  289. This needed argument specifies the version number (the number before the
  290. dot).
  291. Use @{fg highlight}0@{fg text} for alpha versions and @{fg highlight}1@{fg text} for the first release version.
  292. You should increase the version number only when major changes and
  293. improvements are done.
  294. @ENDNODE
  295. ###########################################################################
  296. @NODE "PROJECTNAME"
  297.                                PROJECTNAME/A
  298. This needed argument should be the name of your project. It will be used
  299. for the naming of the RevUp revision storage file ('projectname_rev.rev'),
  300. the C header file ('projectname_rev.h') and the assembly include file
  301. ('projectname_rev.i').
  302. Is is also used for building the version strings found in the
  303. header/include files, so keep care of the right capitalisation.
  304. @ENDNODE
  305. ###########################################################################
  306. @NODE "DEPENDENCIES"
  307.                                DEPENDENCIES/M
  308. RevUp checks the dates of the dependency files against the revision storage
  309. file. Therefore it's possible to update the revision number only if certain
  310. parts of the project are changed.
  311. @ENDNODE
  312. ###########################################################################
  313. @NODE "REVISION"
  314.                                   REV/K/N
  315. Explicitly set the revision to a specific value. Normally RevUp gets the
  316. old revision from projectname_rev.rev and increments it by 1.
  317. @ENDNODE
  318. ###########################################################################
  319. @NODE "BETA"
  320.                                   BETA/S
  321. Enables the beta version count. If BETA is given the first time the
  322. revision is incremented as on a normal call. Additonally a beta count
  323. storage file is created. The beta count starts at 1 as the revision does.
  324. Assume that version is 1 and revision is 1, with BETA specified the
  325. header/include file will look like this:
  326. @{"SuperTool_rev.h" LINK HEADERBETA}, @{"SuperTool_rev.i" LINK INCLUDEBETA}
  327. On every following call with BETA, only the beta count will be incremented,
  328. the revision will stay at 2.
  329. When the beta stage of your program is finished call RevUp without BETA.
  330. The beta count storage file will be deleted and VERS will now look like
  331. this:
  332. @{FG HIGHLIGHT}#define    VERS "SuperTool 1.2"@{FG TEXT}
  333. That means all beta information removed.
  334.                                    NOTE
  335. You should not publicly distribute versions of your program containg a
  336. VERSTAG with beta information, because this string does not follow the
  337. AmiTech version string standard. Although all your beta testers will be
  338. able to correctly display the version information with the current version
  339. command (v40.1).
  340.                                    HINT
  341. Using the beta switch avoids to increment the revision on each compilation,
  342. therefore giving shorter revision numbers for your programs public
  343. releases.
  344. BETA is only defined in the header file if specified in the commandline. So
  345. you could easily include additional debugging code like that:
  346. @{FG HIGHLIGHT}#ifdef BETA
  347.     kprintf("Variable x contains: %ld", x);
  348. #endif@{FG TEXT}
  349. @ENDNODE
  350. ###########################################################################
  351. @NODE "C"
  352.                                     C/S
  353. Set this switch to generate a header file for C language. This is the
  354. default language. Unless you don't specify @{"ASM" LINK ASM} or @{"OBERON" LINK OBERON} a C headerfile
  355. will always be generated.
  356. Examples: @{"Revup 1 SuperTool C EXTRA" LINK HEADER}, @{"Revup 1 SuperTool C EXTRA BETA" LINK HEADERBETA} 
  357. For the old RevUp 1.2 behaviour (always generate C and ASM output):
  358.     @{FG HIGHLIGHT}Revup 1 SuperTool C ASM@{FG TEXT}
  359. @ENDNODE
  360. ###########################################################################
  361. @NODE "ASM"
  362.                                    ASM/S
  363. Set this switch to generate an include file for 68k assembly language. This
  364. switch disables the default @{"C" LINK C} headerfile generation.
  365. Examples: @{"Revup 1 SuperTool ASM EXTRA" LINK INCLUDE}, @{"Revup 1 SuperTool ASM EXTRA BETA" LINK INCLUDEBETA} 
  366. @ENDNODE
  367. ###########################################################################
  368. @NODE "OBERON"
  369.                                    OBERON/S
  370. Set this switch to generate a Oberon definition module. This switch
  371. disables the default @{"C" LINK C} headerfile generation.
  372. Note that the Oberon module differently from the C and Assembly include
  373. files always @{U}defines@{UU} the VersTag variable.
  374. Examples: @{"Revup 1 SuperTool OBERON EXTRA" LINK MODULE}, @{"Revup 1 SuperTool OBERON EXTRA BETA" LINK MODULEBETA} 
  375. @ENDNODE
  376. ###########################################################################
  377. @NODE "LOG"
  378.                                    LOG/S
  379. Appends history information to the <projectname>_rev.log file. The user is
  380. prompted for changes information in the shell. Enter them and end with a
  381. blank line or EOF (press CTRL and \\). An empty log message does not append
  382. the revision header to the log file.
  383. WShell users please note that the CNC: display handler has a bug, that
  384. causes the line terminated with EOF to be lost. Enter a blank line instead.
  385. @ENDNODE
  386. ###########################################################################
  387. @NODE "ENVVAR"
  388.                                  ENVVAR/S
  389. Sets an environment variable for naming the archive of your software.
  390. Example:    @{FG HIGHLIGHT}RevUp 1 SuperTool ENVVAR@{FG TEXT}
  391. Sets the envvar SUPERTOOL to SuperTool1_2, if @{"BETA" LINK "BETA"} is specified
  392. to SuperTool1_2b1.
  393. Now pack your archive like this:
  394.     @{FG HIGHLIGHT}LhA a $SUPERTOOL SuperTool SuperTool.guide SuperTool.readme@{FG TEXT}
  395. @ENDNODE
  396. ###########################################################################
  397. @NODE "EXTRA"
  398.                                   EXTRA/S
  399. Adds some extra information to the header/include files which are not
  400. generated by BumpRev!
  401. I'm thinking about dropping this switch. Contact me if you think there are
  402. any reasons why the extra defintions should not be generated.
  403. @ENDNODE
  404. ###########################################################################
  405. @NODE "TINY"
  406.                                   TINY/S
  407. Supresses printing of the copyright message, therefore giving less output.
  408. @ENDNODE
  409. ###########################################################################
  410. @NODE "HISTORY" "What's new?"
  411.                                   HISTORY
  412. 1.1 (18.8.94) Release 
  413. First public release.
  414. 1.2 (4.9.94) Release
  415. NEW: @{"BETA" LINK BETA} switch enables beta version count.
  416. 1.3 (17.11.95) Release
  417. NEW: @{"OBERON" LINK OBERON} switch enables Oberon definition module generation.
  418. NEW: NOC changed to @{"C" LINK C} (now default language), NOASM changed to @{"ASM" LINK ASM}.
  419. NEW: More comprehensive error messages.
  420. NEW: @{"LOG" LINK LOG} switch enables interactive logfile generation.
  421. NEW: @{"ENVVAR" LINK ENVVAR} switch enables envvar generation.
  422. 1.4 (8.1.96) Release
  423. FIX: RevUp no longer displays an error message, if file to overwrite didn't already exist.
  424. NEW: UserName is now always appended to the log file, even if HostName is not set.
  425. NEW: TIME to logfile. VERSTAG to stdout. Empty log messages are now possible.
  426. @ENDNODE
  427. @node Index "Index"
  428. @{b}  A@{ub}
  429.   @{" Archive Contents           " Link CONTENTS}
  430.   @{" ASM                        " Link ASM}
  431. @{b}  B@{ub}
  432.   @{" BETA                       " Link BETA}
  433. @{b}  C@{ub}
  434.   @{" C                          " Link C}
  435.   @{" Copyright Information      " Link COPYRIGHTS}
  436. @{b}  D@{ub}
  437.   @{" DEPENDENCIES               " Link DEPENDENCIES}
  438. @{b}  E@{ub}
  439.   @{" ENVVAR                     " Link ENVVAR}
  440.   @{" EXTRA                      " Link EXTRA}
  441. @{b}  H@{ub}
  442.   @{" HEADER                     " Link HEADER}
  443.   @{" HEADERBETA                 " Link HEADERBETA}
  444.   @{" How is it used?            " Link USAGE}
  445.   @{" How to install             " Link INSTALLATION}
  446. @{b}  I@{ub}
  447.   @{" INCLUDE                    " Link INCLUDE}
  448.   @{" INCLUDEBETA                " Link INCLUDEBETA}
  449. @{b}  L@{ub}
  450.   @{" LOG                        " Link LOG}
  451. @{b}  M@{ub}
  452.   @{" MODULE                     " Link MODULE}
  453.   @{" MODULEBETA                 " Link MODULEBETA}
  454. @{b}  O@{ub}
  455.   @{" OBERON                     " Link OBERON}
  456. @{b}  P@{ub}
  457.   @{" PROJECTNAME                " Link PROJECTNAME}
  458. @{b}  R@{ub}
  459.   @{" REVISION                   " Link REVISION}
  460.   @{" RevUp                      " Link MAIN}
  461. @{b}  T@{ub}
  462.   @{" TINY                       " Link TINY}
  463. @{b}  V@{ub}
  464.   @{" VERSION                    " Link VERSION}
  465. @{b}  W@{ub}
  466.   @{" What do you need to run it?" Link REQUIREMENTS}
  467.   @{" What does it?              " Link DESCRIPTION}
  468.   @{" What's new?                " Link HISTORY}
  469. @endnode
  470.